/*
 * Copyright 2012 Gayan Perera
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/
package gap.maven.script.components.api;


import java.io.File;

/**
 * Represents a maven artifact file. Maven poms are not represented by this interface.
 * An instance of this interface can be obtained from the {@link ArtifactFileFactory}.
 * 
 * @author gayan
 *
 */
public interface ArtifactFile extends BaseArtifact {
    
    /**
     * Create a link to this artifact at the location specified by the <code>linkPath</code>. The OS specific 
     * linking command will be used to perform this task. Currently this supports OS which contains the commands
     * ln (which is used in linux) or mklink (used in windows 7).
     * 
     * @param linkPath file path where the link must be created. This must contain the file name as well which will be
     * the link name.
     * @return <code>true</code> if the link was created successfully, else returns <code>false</code>.
     */
    boolean link(String linkPath);

    /**
     * Copy the artifact file to the given destination directory.
     * @param destDir Path to the directory where the file must be copied. This will create the directory structure
     * if it doesn't exist.
     * @return File object that represents the copied file or null if the operation failed.
     */
    File copy(String destDir);
    
    /**
     * Returns the POM file for this artifact.
     * @return instance of {@link POMArtifactFile}.
     */
    POMArtifactFile getPOM();
    
    /**
     * Extract the current file if it is an archive file. Trying to extract a non archive file will return false.
     * The error cause to fail will be logged.
     * <b>Note:</b> jar files will also be extracted since they are considered as archives.
     * 
     * @param toDir directory to extract.
     * @param patterns array of patterns to selected files which should extract. 
     * Passing empty will extract all the files.
     * @return <code>true</code> if the extraction was successful, else <code>false</code>.
     */
    boolean extract(File toDir, ExtractorPattern... patterns);
}
